This vignette gives an overview of the USTerritoryMapping R package, which seeks to make creating categorical choropleth maps of the US that include the US territories a little bit easier!
First load the package.
library(USTerritoryMapping)To use this package, you will need to have a data frame with two columns:
fipscodes.rda is provided to facilitate #2.For this vignette, we’ll be using the two provided datasets census.uninsured19 and cdc.cvd. census.uninsured19 provides an example of a dataset with complete data for all 50 states, D.C., and the 5 US territories, while cdc.cvd is missing values for territories.
data(census.uninsured19)
data(cdc.cvd)We can see that each dataset has these two components. In census.uninsured19: 1. “Percent.Cat: the Percentage Ages 19 or Under with No Health Insurance 2.”STUSPS": the two letter US Postal Service code
class(census.uninsured19$Percent.Cat)
#> [1] "factor"
table(census.uninsured19$Percent.Cat)
#>
#> Less than 5% 5% to <10% 10% or Greater
#> 29 22 5
head(census.uninsured19$STUSPS)
#> [1] "PA" "CA" "WV" "UT" "NY" "DC"In cdc.cvd:
class(cdc.cvd$data.cat)
#> [1] "character"
table(cdc.cvd$data.cat)
#>
#> Q1 (166 to < 198) Q2 (198 to < 215) Q3 (215 to < 248) Q4 (248 to 326)
#> 13 13 12 13
head(cdc.cvd$LocationAbbr)
#> [1] "AL" "AK" "AZ" "AR" "CA" "CO"Start by defining the fill category colors with their factor labels.
colors.census <- c("Less than 5%" = "#feebe2",
"5% to <10%" = "#f768a1",
"10% or Greater" = "#7a0177")Then specify any required parameters of the function (see documentation for details).
map1_categorical(data = census.uninsured19,
join_var = "STUSPS",
fill_var = "Percent.Cat",
fill_color = colors.census,
legend_name = "Percent Uninsured",
territory_label_color = "black",
title = "Figure 1. Percent Uninsured, Ages <19 Years",
save.filepath = "saved-maps/map1-uninsure.png")Let’s say we wanted to add a border to highlight specific states or territories. We’ll first define a vector of US postal service IDs (in this example, Oregon, Wisconsin, Virginia, and USVI) and then feed this into the border_ids parameter.
border <- c("OR", "WI", "VA", "VI")
map1_categorical(data = census.uninsured19,
join_var = "STUSPS",
fill_var = "Percent.Cat",
fill_color = colors.census,
legend_name = "Percent Uninsured",
title = "Figure 1. Percent Uninsured, Ages <19 Years",
border_ids = border,
border_color = "red",
border_linewidth = 1,
save.filepath = "saved-maps/map1-uninsure2.png")Sometimes we may want to remove the inset box outline, which we can do by specifying inset_box_color = "white".
We also highlight an additional option of removing the territory labels by specifying territory_label_color = "white".
colors.cdc <- c("Q1 (166 to < 198)" = "#ffffcc",
"Q2 (198 to < 215)" = "#a1dab4",
"Q3 (215 to < 248)" = "#41b6c4",
"Q4 (248 to 326)" = "#225ea8")
map1_categorical(data = cdc.cvd,
join_var = "LocationAbbr",
fill_var = "data.cat",
fill_color = colors.cdc,
fill_linewidth = 1.2,
fill_linecolor = "black",
inset_box_color = "white",
territory_label_color = "white",
legend_name = "CVD Mortality per 100,000",
border_ids = border,
border_color = "red",
border_linewidth = 1.5,
save.filepath = "saved-maps/map1-cvd.png") We love maps of the territory geometries, but you might also want a map with the territory labels.
colors.census <- c("Less than 5%" = "#feebe2",
"5% to <10%" = "#f768a1",
"10% or Greater" = "#7a0177")
border <- c("OR", "WI", "VA", "VI")
map2_categorical(data = census.uninsured19,
join_var = "STUSPS",
fill_var = "Percent.Cat",
fill_color = colors.census,
legend_name = "Percent Uninsured",
title = "Figure 1. Percent Uninsured, Ages <19 Years",
border_ids = border,
border_color = "red",
border_linewidth = 1,
save.filepath = "saved-maps/map2-uninsure.png")Note that in the current package version, territory labels cannot be highlighted with a border, even when specified in the border ID vector.
colors.cdc <- c("Q1 (166 to < 198)" = "#ffffcc",
"Q2 (198 to < 215)" = "#a1dab4",
"Q3 (215 to < 248)" = "#41b6c4",
"Q4 (248 to 326)" = "#225ea8")
map2_categorical(data = cdc.cvd,
join_var = "LocationAbbr",
fill_var = "data.cat",
fill_color = colors.cdc,
fill_linewidth = 1.2,
fill_linecolor = "black",
inset_box_color = "white",
legend_name = "CVD Mortality per 100,000",
border_ids = border,
border_color = "red",
border_linewidth = 1.5,
save.filepath = "saved-maps/map2-cvd.png")